Callblast API Endpoint
=======================

Overview
--------

The Callblast API allows external systems to trigger a voice broadcast by sending a structured JSON payload.

This endpoint is intended for backend integrations and programmatic usage.

Authentication
--------------

Authentication is based on a combination of two required fields:

- ``isp``: (in the payload): Acts like a **username**, identifying the company or ISP
- ``api_key``: (in the URL parameters): Acts like a **password**, verifying the authenticity of the request

Both the ``isp`` and ``api_key`` must be provided to successfully authenticate. The system cross-references these values to validate the request and determine the appropriate company configuration.

Upon successful authentication, the system uses the ``isp`` to retrieve related settings such as caller ID, account code, and other necessary routing metadata. If the ``api_key`` does not match the stored credentials for the provided ``isp``, the request will be rejected.

POST api/callblast_request
--------------------------

Submit a voice call job to the system.

Headers
-------

- ``Content-Type: application/json``

Example Request Parameters
--------------------------
**https://tracker.serverplus.com/api/callblast_request?api_key=``company-api-key-here``**

Example Request Body
--------------------

.. code-block:: json

    {
        "isp": "1001",
        "message": "Your appointment is confirmed for tomorrow at 3 PM.",
        "numbers": [
            "09171234567",
            "09181234567"
        ]
    }

Payload Fields
--------------

+-------------+---------------+-----------------------------------------------------------+
| Field       | Type          | Description                                               |
+=============+===============+===========================================================+
| isp         | string        | Company or ISP ID assigned to you                         |
+-------------+---------------+-----------------------------------------------------------+
| message     | string        | Text to convert to speech (5–1000 characters)             |
+-------------+---------------+-----------------------------------------------------------+
| numbers     | list of str   | Phone numbers (10–15 digit-only strings, no symbols)      |
+-------------+---------------+-----------------------------------------------------------+

Parameter Fields
----------------

+-------------+---------------+-----------------------------------------------------------+
| Field       | Type          | Description                                               |
+=============+===============+===========================================================+
| api_key     | string        | Company-specific authentication token                     |
+-------------+---------------+-----------------------------------------------------------+

Validation Rules
----------------

- ``message`` is required; must be between 5 and 1000 characters
- ``numbers`` must be a list of digit-only strings, each 10–15 characters
- ``api_key`` must be present and valid
- ``isp`` and ``api_key`` are jointly validated; mismatches are rejected
- The ``isp`` is used to fetch caller ID, account code, and other metadata

Success Response
----------------

.. code-block:: json

    {
        "status": "queued",
        "targets": 2
    }

-  ``status``: If set to ``queued``, it means the callblast request was successful and the numbers have been queued.
-  ``targets``: The total number of phone numbers successfully queued for the callblast.

Error Responses
---------------

.. code-block:: json

    {
        "error": "Missing or blank required fields: message, numbers"
    }

.. code-block:: json

    {
        "error": "Message is too short (minimum is 5 characters)."
    }

.. code-block:: json

    {
        "error": "The following phone numbers are invalid: abc123, 09876"
    }

.. code-block:: json

    {
        "error": "No valid phone numbers provided."
    }

.. code-block:: json

    {
        "error": "API request failed with status 500: Internal Server Error"
    }

.. code-block:: json

    {
        "error": "Unexpected failure: <detailed error message>"
    }

Notes
-----

- Caller ID, account code, and agent details are automatically resolved based on the ``isp`` and the ``api_key``.
- If any phone number fails validation, the entire request is rejected.